.pl 29.7c
.\\" $Id: smdata.1,v 1.3 2004/07/11 08:04:47 bhepple Exp $
.so extramac
.TH SMDATA 1 "Tue Oct 27 1992" "\&\(co Bob Hepple"
.UC 4
.SH NAME
smdata \- visual editor for data using
.B "Screen Manager"
forms definitions.
.SH SYNOPSIS
.B smdata
[
.B \-m|f
]
.I screenfile
[
.I :screen\-name
] [
.I datafile
[
.IR datafile ".\|.\|. ]"
]
.SH DESCRIPTION
.B smdata
interactively edits
data files according to the forms and data definition in the
.I screenfile
(probably built by
.BR smcreate (1))
The
.I screenfile
may
contain one or more screen definitions which can be used to format the
data on-screen in more or less useful ways.
For example, the data may
be a simple data file like an address list with one record per line
with fields like:
.LP
.RS
.nf
\fBNAME;ADDRESS;PHONE;FAX\fR
.fi
.RE
.LP
Note that the data fields can be variable length and are delimited in
this example by
.B \';\'.
Also, fields on the screen will scroll left
and right to accomodate data longer than the field width.
Thus,
.B smdata
allows easy visual editing of data that is compatible with the
standard UNIX utilities such as
.BR sort (1),
.BR grep (1)
and
.BR awk (1)
and
.B smdata
thereby forms a natural extension to the UNIX
operating system.
.LP
Although
.B smdata
is at its best on a
workstation under X\-Windows, it can easily be used on terminals in a
time-sharing environment or even on stand alone PC's under MS-DOS all
the while maintaining compatibility and portability of data and screen
files across all platforms.
(Under MS-DOS, you might want to get the
MKS UNIX utilities to provide
.BR sort (1),
.BR grep (1)
and
.BR awk (1)).
.LP
The data can be displayed one record at a time or in a
scrolling list.
.LP
Variable data formats within a file, each with
its own screen layout can be defined.
In this case,
.B smdata
needs to
be told how to distinguish each type.
Presently the only mechanism is
to assign one of the fields to be a 'tag'; e.g.:
.LP
.RS
.nf
\fBPERSONAL;NAME;ADDRESS;PHONE
.br
WORK;NAME;POSITION;COMPANY;ADDRESS;PHONE;FAX\fR
.fi
.RE
.LP
In this
case, the first field acts as the tag and the file contains only two
record types.
.LP
Simple relations between separate data files can be
created.
For example, a list of books may be related to a list of
authors if both lists have screens in a
.I screenfile:
.LP
.RS
.nf
\fBTITLE;AUTHOR;PUBLISHER;DATE
.br
AUTHOR;ADDRESS;PHONE\fR
.fi
.RE
.LP
Both master file(s) and data files can be displayed on one physical
screen provided the two logical screens that define each data set do
not overlap.
The detail set can scroll provided
.B smdata
knows what
constitutes a unique record (the 'constant' part in
.BR smcreate ).
.LP
If
.I screen-name
is given, then that screen is used rather than
the default for the file.
.PP
Multiple
.I datafiles
may be given to override the defaults supplied in the
.I screenfile.
.SH OPTIONS
.TP
.B -m
use memory (the heap) for temporary file storage.
This is fast but may
be limited in size depending on the system architecture (e.g. very
limited on MS-DOS).
Note that the \fISort\fR function creates an
internal list of the sort keys plus about 4 bytes per record and can
add substantially to the RAM required.
In other words, if you run out
of RAM, use an external sort.
.TP
.B -f
use disc files for temporary storage.
This is potentially slower than
the
.B -m
option (particularly in moveing backwards through a file) but may
allow larger files to be handled.
.SH KEYS & SCREENS
When
.B smdata
starts up, the screen is immediately placed on the first record of the
data and the softkeys are as in Figs. 1, 2 and 3.
.LP
.ne 7v
.BB
.PS 6.5i
.so sm_data.sky
.PE
.EB "Fig. 1. Editing Softkeys (a)"
.LP
.ne 7v
.BB
.PS 6.5i
.so sm_other.sky
.PE
.EB "Fig. 2. Editing Softkeys (b)"
.LP
Note that the \fB'*'\fR on the \fIIgnore Case\fR softkey toggles on
and off to indicate whether case is significant in searches or not.
The \fIAgain\fR command repeats the previous \fIFind First\fR, \fIFind
Last\fR or \fISearch & Replace\fR commands.
.LP
.ne 7v
.BB
.PS 6.5i
.so sm_sort.sky
.PE
.EB "Fig. 3. Editing Softkeys (c)"
.TP
.B Sort
If \fISort Keys\fR have been defined for the file then they are used
to re-order the file.
Otherwise, the file will be sorted on the
current field and you are prompted for whether the sort should be
ascending or descending and whether a numeric sort should be done (the
default is an ascending Ascii sort).
The current value of the \fIIgnore Case\fR softkey is used in the sort.
Note that this
function is only available if the file is held in memory (as opposed
to being held in temporary files).
The \fISort\fR function creates a
temporary internal list of the sort keys plus pointers to the data
(thus equal in size to (sum of key item sizes plus 4 bytes) per record).
.B smcreate
can also set up sort keys so that the file is ordered at the time it is
written.
(On PC's, this requires the use of a third party sort utility
such as the MKS system).
.TP
.B "Popup Master"
This is only valid if the cursor is in a field which has a master or
key value assigned to it (i.e. in a multi-file database).
A popup
screen of possible values for this field is shown and the cursor can
move up and down it.
To return to normal data file editing, press
return.
The line in the popup that was selected is then offered as a
replacement for the current contents.
If this is accepted,
.B smdata
offers to replace all occurances of the old value in the detail file
with the new value.
.TP
.B "Edit Master"
Again, this is only valid if the cursor is in a field which has a master or
key value assigned to it (i.e. in a multi-file database).
The master
file is generally protected from accidental editing until this command
is given.
To return to normal data editing, press it again.
If the key
value in the master file is changed you are prompted to change all the
old values in the detail file to the new value as well.
You don't have
to do this.
.TP
.B "Change Rec. Type"
In a file with variant record types (a tagged file) this button
presents you with a list of alternative record layouts for the present
record.
If a new value is picked the record is converted - some data
may be lost in the conversion.
.ne 27v
.SH "THE WHERE SCREEN"
.SD
.ie n \{\
.nf
.na
.so sm_where.dmp
.fi
.ad b
\}
.el \{\
.so sm_where.scr
\}
.if t \f(CB
.if n .sp
.ie n \{\
.PS 6.5i
.nf
.na
.so sm_where.sky
.fi
.ad b
.PE
\}
.el \{\
.PS 6.5i
.so sm_where.sky
.PE
\}
.EB "Fig. 4. Where Screen."
.LP
In short, the
.B WHERE
screen (usually reached via Meta-W or function keys) allows you to
specify
.B where
in the data you want to look and then
.B what
you want to do with it.
.LP
The
.B where
part can be specified as a range of record numbers (inclusive - the
default is to search from 0 to $, the last record) and then in the
four lines labelled
.B WHERE,
.B AND,
.B AND
and
.B AND!
These are provided to further refine the search.
Thus to find records
where the company_name is "Acme Ltd.", put
.I $company_name
in the field marked
.B WHERE,
put
.B =
in the relation column and
.I "Acme Ltd."
in the rightmost field (marked
.I "<field/value/regexp>."
Then press the
.B "Do it"
function key and the screen should show the first record that matches.
.LP
Note that field names are prefixed by a
.B $
to distinguish them from plain text.
Strictly speaking, fieldnames
should also be suffixed with
.B $
as in:
.LP
.RS
.nf
.I "$company_name$"
.fi
.RE
.LP
but this is only required in complex functions such as the
concatenation of two fields, as in:
.LP
.RS
.nf
.I "$company_name$$phone_number$"
.fi
.RE
.LP
or when concatenating the contents of a field with some plain text, as
in:
.LP
.RS
.nf
.I "$company_name$some other text"
.fi
.RE
.LP
The
.B WHERE
screen has popups available to simplify filling in the fields.
Access
the popup fields (they are marked with \fB'^'\fR to the right of the
field) by pressing \fBMeta-m\fR, pressing the right mouse button or in
.BR xctool ,
by pressing the button marked
.BR Popup .
.LP
The
.B relation
field can be the usual string comparisons (all modified by the value
of
.BR "ignore case" ):
.RS
.TP
.B =
Exact string match
.TP
.B "<, >, >=, <="
The usual string comparisons (note -
.B not
numeric or date calculations).
.TP
.B \-
use a regular expression match (see
.BR ed (1))
.TP
.B "!"
Does
.B not
match.
Thus
.B !=
means "is not equal to",
.B !>
means "is not greater than" and
.B !-
means "does not match the regular expression".
.RE
.LP
There are three ways to alter fields with the
.B WHERE
screen, namely:
.LP
.RS
to
.B delete
the matching records,
.LP
to
.B change
fields in the matching records, and
.LP
to
.B output
the matching records to an external file.
.RE
.LP
In each case, when a match is found the data is displayed and the
function keys are labelled
.BR "Do it" ,
.BR "Skip" ,
.B "Do all" and
.BR "Cancel" .
.LP
The
.B change
function allows you to change a specified field (not necessarily the
one used in the search) to a new value which can be a combination of
field values, literals or regular expression replacements as in:
.LP
.RS
.nf
.I "$company_name$some literal text\e1"
.fi
.RE
.LP
which takes the value of the field
.IR "company_name" ,
adds
.I some
literal text to it and finally adds the first remembered pattern from
the original regular expression.
.LP
A special value is
.B $date
which applies the current date in the form \fI921027\fR (hopefully,
the Americans will be as happy with this format as everyone else in
the world!).
.SH MAIN KEYS
As these are usually seen at the end of a session, they are documented
here.
.LP
.ne 7v
.BB
.PS 6.5i
.so smdamain.sky
.PE
.EB "Fig. 5. Main Softkeys."
.LP
The main item of interest here is the \fIStore DataFile\fR softkey
which brings up the screen as in Fig. 6.
.LP
.ne 13v
.SD
.ie n \{\
.nf
.na
.so strfiles.dmp
.fi
.ad b
\}
.el \{\
.so strfiles.scr
\}
.if t \f(CB
.if n .sp
.fi
.PS 6.5i
.so strfiles.sky
.PE
.EB "Fig. 6. Store DataFile Screen."
.LP
Each file that is described in the \fIscreenfile\fR is listed and you
have on opportunity to select whether or not to save it and which file
to save it in.
The default is to only save files that have been
changed and to save them in their original filenames.
The \fISave
all\fR and \fISave none\fR buttons allow you to set the save toggles
collectively.
As with other
.B "Screen Manager"
programs, if you request an exit with files that need changing, you
are invited to save them first.
If you select \fICancel\fR the exit is
cancelled.
(Except on PC's) if the file has sort keys defined, it is
sorted as it is written (it is piped through
.BR sort (1)).
Note that if you return to editing after sorting and writing, the file
will not necessarily be ordered - you need to read the sorted file in
again.
.SH "USING A MOUSE WITH SMDATA"
A mouse really makes things move along.
Under Sun's OpenWindows, you
can use a mouse (and OpenLook buttons) by running
.B smdata
under the special shell
.BR xctool (1).
Under MS-DOS, the Microsoft serial mouse is supported through the
standard mouse driver version 5.0.
In any case, the mouse buttons are
very simply mapped with Left (\fISelect\fR under OpenWindows) being
the main player.
The right button (\fIMenu\fR under OpenWindows)
allows field values to be popped up if they have lists associated with
them (usually denoted with \fB'^'\fR to the right of the field).
.SH "ALTERNATIVES TO META"
Not having \fBMeta\fR on a terminal or window is a royal pain, but you
can work around in one of two ways.  Hopefully one of these will work
for you! (Better still, get your vendor to fix the terminal - Sun's
Terminal emulators under OpenWindows 1/2/3 are a case in point.
Curiously, \fBMeta-\fR used to work properly under SunView! The 
.BR xterm (1)
shipped with OpenWindows does appear to work correctly!)
.LP
As an alternative to \fBMeta-A\fR for instance, you can press either
the \fBEscape\fR key or the \fBf9\fR key and then \fBA\fR.
An
.B M-
appears in the last line of the screen indicating that the next
character will be treated as if it were meta-shifted.
To cancel it
just press \fBEscape\fR or \fBf9\fR again.
.SH FILES
.TP
.B *.dat
Default name for
.B "Screen Manager"
screen definition files.
.TP
.B *.txt
Default name for data files.
.TP
.B *~
Before files are saved, the old file is moved to *~ as a form of
backup (*.~?? under MS-DOS).
Thus \fIproject.txt\fR would be backed
up to \fIproject.txt~\fR (\fIproject.~tx\fR under MS-DOS)
.TP
.B $LOCAL/lib/scrmgr/*
For examples of the use of
.B smdata
including:
.TP
.B $LOCAL/lib/scrmgr/addr
a simple address list and utilities.
.BR sort (1),
.BR awk (1)
(actually
.BR nawk (1)
under SunOS) and
.BR groff (1)
are used to take the data file
.B addr.txt
generated by
.B smdata
and produce a sorted report ready to be typeset.
If you don't have
.BR groff (1)
or another
.BR troff (1)
compatible typesetting system, use the simple command:
.LP
.RS
\fBawk -f no_groff.awk addr.txt > addr\fR
.RE
.TP
.B $LOCAL/lib/scrmgr/passwd
A simple editor for the
.B /etc/passwd
file.
.SH ENVIRONMENT
.TP
.B TMP
If specified,
temporary files (if used) are put here.
Otherwise \fI/tmp\fR is used.
.TP
.B SHELL
Used by the global command SM_SHELL_C (usually bound to
Meta-!) if set otherwise
.BR sh (1)
is used.
.SH "SEE ALSO"
Postscript version of these man pages which have screenshots -
probably in /usr/share/doc/scrmgr-X.Y.
.LP
.so smdata.lst
.SH AUTHOR
Bob Hepple <bhepple@freeshell.org>
.SH COPYRIGHT
Copyright \(co 1991-2002 Bob Hepple
